.. _envoy_api_file_api/eds.proto: EDS === .. _envoy_api_msg_LbEndpoint: LbEndpoint ---------- `[LbEndpoint proto] `_ .. code-block:: json { "endpoint": "{...}", "health_status": "...", "metadata": "{...}", "load_balancing_weight": "{...}", "priority": "{...}" } .. _envoy_api_field_LbEndpoint.endpoint: endpoint (:ref:`Endpoint `) .. _envoy_api_field_LbEndpoint.health_status: health_status (:ref:`HealthStatus `) Optional health status when known and supplied by EDS server. .. _envoy_api_field_LbEndpoint.metadata: metadata (:ref:`Metadata `) The endpoint metadata specifies values that may be used by the load balancer to select endpoints in a cluster for a given request. The filter name should be specified as "envoy.lb". An example boolean key-value pair is "canary", providing the optional canary status of the upstream host. This may be matched against in a route's ForwardAction metadata_match field to subset the endpoints considered in cluster load balancing. TODO(htuch: [V2-API-DIFF] Need to plumb this through Envoy and have everywhere that canary is used be capable of working on metadata. .. _envoy_api_field_LbEndpoint.load_balancing_weight: load_balancing_weight (`UInt32Value `_) The optional load balancing weight of the upstream host, in the range 1 - 100. Envoy uses the load balancing weight in some of the built in load balancers. The load balancing weight for an endpoint is divided by the sum of the weights of all endpoints in the endpoint's locality to produce a percentage of traffic for the endpoint. This percentage is then further weighted by the endpoint's locality's load balancing weight from LocalityLbEndpoints. If unspecified, each host is presumed to have equal weight in a locality. .. _envoy_api_field_LbEndpoint.priority: priority (`UInt32Value `_) Optional: the priority for this LbEndpoint. If unspecified this will default to the highest priority (0). Under usual circumstances, Envoy will only select endpoints for the highest priority (0). In the event all endpoints for a particular priority are unavailable/unhealthy, Envoy will fail over to selecting endpoints for the next highest priority group. Priorities should range from 0 (highest) to N (lowest) without skipping. .. _envoy_api_msg_LocalityLbEndpoints: LocalityLbEndpoints ------------------- `[LocalityLbEndpoints proto] `_ All endpoints belonging to a Locality. .. code-block:: json { "locality": "{...}", "lb_endpoints": [], "load_balancing_weight": "{...}" } .. _envoy_api_field_LocalityLbEndpoints.locality: locality (:ref:`Locality `) .. _envoy_api_field_LocalityLbEndpoints.lb_endpoints: lb_endpoints (:ref:`LbEndpoint `) .. _envoy_api_field_LocalityLbEndpoints.load_balancing_weight: load_balancing_weight (`UInt32Value `_) Optional: Per region/zone/sub_zone weight - range 1-100. The load balancing weight for a locality is divided by the sum of the weights of all localities to produce the effective percentage of traffic for the locality. If unspecified, each locality is presumed to have equal weight in a cluster. .. _envoy_api_msg_EndpointLoadMetricStats: EndpointLoadMetricStats ----------------------- `[EndpointLoadMetricStats proto] `_ Example load report from a single request: [metric name, metric value] * cpu_seconds, 0.7 * flash_utilization, 75 When aggregating Envoy needs to count how many request's load reports included each metric type, so Envoy can account for requests that don't include that metric type. e.g.: [name, count, sum of values] * cpu_seconds, 10, 17.5 * flash_utilization, 5, 375 .. code-block:: json { "metric_name": "...", "num_requests_finished_with_metric": "...", "total_metric_value": "..." } .. _envoy_api_field_EndpointLoadMetricStats.metric_name: metric_name (`string `_) Name of the metric; may be empty. .. _envoy_api_field_EndpointLoadMetricStats.num_requests_finished_with_metric: num_requests_finished_with_metric (`uint64 `_) Number of calls that finished and included this metric. .. _envoy_api_field_EndpointLoadMetricStats.total_metric_value: total_metric_value (`double `_) Sum of metric values across all calls that finished with this metric for load_reporting_interval. .. _envoy_api_msg_UpstreamLocalityStats: UpstreamLocalityStats --------------------- `[UpstreamLocalityStats proto] `_ These are stats Envoy reports to GLB every so often. Report frequency is defined by LoadAssignmentResponse.interval Stats per upstream region/zone and optionally per subzone .. code-block:: json { "locality": "{...}", "total_successful_requests": "...", "total_requests_in_progress": "...", "total_error_requests": "...", "load_metric_stats": [] } .. _envoy_api_field_UpstreamLocalityStats.locality: locality (:ref:`Locality `) Name of zone, region and optionally endpoint group this metrics was collected from. Zone and region names could be empty if unknown. .. _envoy_api_field_UpstreamLocalityStats.total_successful_requests: total_successful_requests (`uint64 `_) The total number of requests sent by this Envoy since the last report. A single HTTP or gRPC request or stream is counted as one request. A TCP connection is also treated as one request. There is no explicit total_requests field below for a locality, but it may be inferred from: .. code-block:: none total_requests = total_successful_requests + total_requests_in_progress + total_error_requests The total number of requests successfully completed by the endpoints in the locality. These include non-5xx responses for HTTP, where errors originate at the client and the endpoint responded successfuly. For gRPC, the grpc-status values are those not covered by total_error_requests below. .. _envoy_api_field_UpstreamLocalityStats.total_requests_in_progress: total_requests_in_progress (`uint64 `_) The total number of unfinished requests .. _envoy_api_field_UpstreamLocalityStats.total_error_requests: total_error_requests (`uint64 `_) The total number of requests that failed due to errors at the endpoint. For HTTP these are responses with 5xx status codes and for gRPC the grpc-status values {DeadlineExceeded, Unimplemented, Internal, Unavailable, Unknown, DataLoss}. .. _envoy_api_field_UpstreamLocalityStats.load_metric_stats: load_metric_stats (:ref:`EndpointLoadMetricStats `) Stats for multi-dimensional load balancing. .. _envoy_api_msg_ClusterStats: ClusterStats ------------ `[ClusterStats proto] `_ Per cluster stats .. code-block:: json { "cluster_name": "...", "upstream_locality_stats": [], "total_dropped_requests": "..." } .. _envoy_api_field_ClusterStats.cluster_name: cluster_name (`string `_) .. _envoy_api_field_ClusterStats.upstream_locality_stats: upstream_locality_stats (:ref:`UpstreamLocalityStats `) Need at least one. .. _envoy_api_field_ClusterStats.total_dropped_requests: total_dropped_requests (`uint64 `_) Cluster-level stats such as total_successful_requests may be computed by summing upstream_locality_stats. In addition, below there are additional cluster-wide stats. The following total_requests equality holds at the cluster-level: .. code-block:: none sum_locality(total_successful_requests) + sum_locality(total_requests_in_progress) + sum_locality(total_error_requests) + total_dropped_requests` The total number of dropped requests. This covers requests deliberately dropped by the drop_overload policy and circuit breaking. .. _envoy_api_msg_LoadStatsRequest: LoadStatsRequest ---------------- `[LoadStatsRequest proto] `_ .. code-block:: json { "node": "{...}", "cluster_stats": [] } .. _envoy_api_field_LoadStatsRequest.node: node (:ref:`Node `) .. _envoy_api_field_LoadStatsRequest.cluster_stats: cluster_stats (:ref:`ClusterStats `) .. _envoy_api_msg_ClusterLoadAssignment: ClusterLoadAssignment --------------------- `[ClusterLoadAssignment proto] `_ Each route from RDS will map to a single cluster or traffic split across clusters using weights expressed in the RDS WeightedCluster. With EDS, each cluster is treated independently from a LB perspective, with LB taking place between the Localities within a cluster and at a finer granularity between the hosts within a locality. For a given cluster, the effective weight of a host is its load_balancing_weight multiplied by the load_balancing_weight of its Locality. .. code-block:: json { "cluster_name": "...", "endpoints": [], "policy": "{...}" } .. _envoy_api_field_ClusterLoadAssignment.cluster_name: cluster_name (`string `_) .. _envoy_api_field_ClusterLoadAssignment.endpoints: endpoints (:ref:`LocalityLbEndpoints `) .. _envoy_api_field_ClusterLoadAssignment.policy: policy (:ref:`ClusterLoadAssignment.Policy `) .. _envoy_api_msg_ClusterLoadAssignment.Policy: ClusterLoadAssignment.Policy ---------------------------- `[ClusterLoadAssignment.Policy proto] `_ .. code-block:: json { "drop_overload": "..." } .. _envoy_api_field_ClusterLoadAssignment.Policy.drop_overload: drop_overload (`double `_) Percentage of traffic (0-100) that should be dropped. This action allows protection of upstream hosts should they unable to recover from an outage or should they be unable to autoscale and hence overall incoming traffic volume need to be trimmed to protect them. [V2-API-DIFF] This is known as maintenance mode in v1. .. _envoy_api_msg_LoadStatsResponse: LoadStatsResponse ----------------- `[LoadStatsResponse proto] `_ .. code-block:: json { "clusters": [], "load_reporting_interval": "{...}" } .. _envoy_api_field_LoadStatsResponse.clusters: clusters (`string `_) Clusters to report stats for. .. _envoy_api_field_LoadStatsResponse.load_reporting_interval: load_reporting_interval (`Duration `_) The default is 10 seconds.